主题
图像识别模块总览 - Overview
本分类做什么
在 大图、内存图或已绑定窗口画面 中，按 模板相似度 或 色差+方向 查找目标位置；部分接口支持 多模板（路径用 | 拼接）、旋转扫描、二值/阈值匹配 与 动画/GIF 时段匹配。返回一般为 JSON 字符串指针（需 GetStringFromPtr + FreeStringPtr），坐标含义因系列而异（屏幕/文件图 vs 相对绑定窗口）。
使用前通常配合 图像处理：GetScreenDataPtr、LoadImage 等得到 OLAImage；绑定窗口场景需先 BindWindow。
一、先分清两条产品线：Match* 与 Find*
二者 不是 简单改名，参数与语义不同。
| 对比项 | Match*（匹配） | Find*（查找） |
|---|---|---|
| 核心参数 | matchVal（0～1 相似度）、type（匹配模式 1～5）、angle（旋转步进）、scale（缩放） | deltaColor（色差串，如 "101010"）、matchVal，无 type/angle 这一套 |
| 典型用途 | 与模板做 结构相似度 匹配，可调 灰度/彩色/透明 等类型（见各页 type 说明） | 在色差容忍下 按扫描方向 找 第一个 或 全部 位置 |
| 结果 | Match*：默认最优一条；带 All 的返回 全部 达标位置 | Find*：无 All → 第一个；带 All → 全部 |
| 方向 | 由算法在区域内搜索最优/全部 | Find* 有 dir（多种扫描顺序，如左上到右下、从中心等） |
选型：需要 type/透明/旋转 时用 Match*；更贴近 颜色偏差 + 扫描顺序、接口更轻时用 Find*。
二、第二维：MatchImage* vs MatchWindows*
| 系列 | 图源与区域 | 坐标系 |
|---|---|---|
| MatchImage* | 源图为 文件路径 或 OLAImage 句柄（整图或已裁好的图） | 相对 该源图 的像素坐标（具体见各接口返回值说明） |
| MatchWindows* | 在 已绑定窗口 上取 矩形区域 (x1,y1,x2,y2)，仅需模板 | 返回 相对绑定窗口 的坐标 |
选型：已 BindWindow 且只关心窗内区域 → MatchWindows*；源图来自文件或内存大图、与绑定无关 → MatchImage*。
三、第三维：Path / Ptr / 混合
模板与源图的数据来源组合（命名即含义）：
| 接口形态 | 源图 | 模板 | 说明 |
|---|---|---|---|
| MatchImageFromPath | 文件路径 | 文件路径 | 最省事，适合磁盘上的源图与模板 |
| MatchImageFromPtr | OLAImage | OLAImage | 双内存，重复匹配时避免反复读盘 |
| MatchImageFromPathAll | 路径 | 路径 | 与上相同，但返回 所有 匹配位 |
| MatchImageFromPtrAll | 指针 | 指针 | 内存版 全部 结果 |
| MatchImagePtrFromPath | OLAImage | 路径 | 源已在内存（如截图句柄），模板仍用文件 |
| MatchImagePtrFromPathAll | OLAImage | 路径 | 上者的 全部 结果版 |
| FindImagePtrFromPath | OLAImage | 路径 | Find 线的混合形态：源已在内存，模板仍用文件 |
| FindImagePtrFromPathAll | OLAImage | 路径 | 上者的 全部 结果版 |
差异要点：
- 无后缀 / 非 All：通常返回 最优一条（文档称默认最优结果）。
- 带 All：同一套参数下仅返回 识别率大于等于阈值 的位置；低于阈值的结果不输出，适合一屏多图标。
- PtrFromPath：减少 模板路径 反复加载时的使用方式，源必须是
LoadImage/GetScreenDataPtr等得到的句柄。 - 多模板加载失败：模板路径可用
\|拼接多张图；默认任一模板不存在或加载失败时整次返回空；可通过全局配置MultiTemplateAbortOnInvalidImage（默认true）控制：false时跳过无效图继续匹配，见 SetConfigByKey。 - 多模板线程：可用
FindImageThreadMode（0 单线程 / 1 多线程 / 2 自动默认）与FindImageThreadCount（默认 4，仅多线程时生效）控制；FromPath/FromPathAll/MatchWindowsFromPath*等共用，见 SetConfig。
MatchImageFromPathAll 等页中 scale 在 All 系列里常标注为 源图缩放；与 MatchImageFromPath 中配合窗口的缩放含义请以 对应详情页 为准，避免混用。
四、MatchWindows*：绑定窗口上的「普通匹配」与「全部」
在 已绑定窗口 的 (x1,y1,x2,y2) 内匹配，模板可为路径或内存。
| 接口 | 模板 | 结果数量 |
|---|---|---|
| MatchWindowsFromPath | 路径 | 最优 |
| MatchWindowsFromPathAll | 路径 | 全部 |
| MatchWindowsFromPtr | OLAImage | 最优 |
| MatchWindowsFromPtrAll | OLAImage | 全部 |
差异：仅 模板 来自路径还是句柄，以及 最优 vs 全部；其余 matchVal、type、angle、scale 与 MatchImage 系一致。
五、MatchWindowsThreshold*：二值化后再匹配（线稿/UI 轮廓）
在普通 MatchWindows* 基础上，增加 colorJson（颜色模型，见 ColorModel），对区域做 二值/分色 后再与模板比对，适合 边缘清晰、颜色单一 的界面元素。
| 接口 | 模板 |
|---|---|
| MatchWindowsThresholdFromPath | 路径 |
| MatchWindowsThresholdFromPathAll | 路径，全部结果 |
| MatchWindowsThresholdFromPtr | OLAImage |
| MatchWindowsThresholdFromPtrAll | OLAImage，全部结果 |
与普通 MatchWindows 的差异：多 colorJson，走 阈值/二值 管线；无 与 MatchImage* 直接一一对应的 Threshold 版本时，以侧栏为准。
六、FindImage* vs FindWindows*（查找线）
与 Match 对照：色差 deltaColor + 相似度 matchVal，无 type/angle。
6.1 全图/文件图：FindImage*
| 接口 | 源与模板 | 结果 |
|---|---|---|
| FindImageFromPath | 均为路径 | 第一个，带 dir |
| FindImageFromPathAll | 均为路径 | 全部（无 dir） |
| FindImageFromPtr | 均为 OLAImage | 第一个，带 dir |
| FindImageFromPtrAll | 均为 OLAImage | 全部 |
| FindImagePtrFromPath | 源 OLAImage，模板路径 | 第一个，带 dir |
| FindImagePtrFromPathAll | 源 OLAImage，模板路径 | 全部 |
6.2 绑定窗口：FindWindows*
| 接口 | 模板 | 结果 |
|---|---|---|
| FindWindowsFromPath | 路径 | 第一个，区域 (x1,y1,x2,y2) + dir |
| FindWindowsFromPathAll | 路径 | 全部 |
| FindWindowsFromPtr | OLAImage | 第一个 |
| FindWindowsFromPtrAll | OLAImage | 全部 |
差异小结：FindImage vs FindWindows = 图源与坐标系（整图 vs 绑定窗区域）；FromPath vs FromPtr = 路径 vs 句柄；PtrFromPath = 源句柄 + 模板路径；无 All = 第一个 + 方向 dir，有 All = 枚举全部。
七、MatchAnimation*：动画 / GIF 场景
在 时间窗 内持续匹配 动态区域（如 GIF），命中即返回，参数含 帧间隔 delay、总时长 time、线程数 threadCount。
| 接口 | 模板来源 |
|---|---|
| MatchAnimationFromPath | 路径 |
| MatchAnimationFromPtr | OLAImage |
与静态 MatchWindows* 的差异：多时间/线程相关参数，用于 动效 而非单帧截图。
八、整图度量（不做滑窗模板搜索）
两张 已对齐的 OLAImage 直接比整体相似度或误差，不是「在大图里找小图」。
| 接口 | 作用 |
|---|---|
| CalculateSSIM | 结构相似性指数（SSIM） |
| IsSameImage | 是否相同（整体判定） |
| CalculateHistograms | 直方图比较 |
| CalculateMSE | 均方误差（MSE） |
与 Match/Find 的区别：无模板在源图上滑动；适用于 两帧对比、整屏是否变化 等。
九、调试与其它
| 接口 | 作用 |
|---|---|
| ShowMatchWindow | 全局开关：找图、找字、识字 等是否 弹窗预览（调试用，正式环境建议关闭） |
十、返回值与后续处理
- 字符串指针：多数返回
long指针，需GetStringFromPtr取 JSON 文本，再FreeStringPtr。 - JSON 解析：可使用 JSON 分类中的
ParseMatchImageJson、GetMatchImageAllCount、ParseMatchImageAllJson等，与多结果、多矩形字段解析配合。 - 最优解与命中判定：
- 非
All系列通常返回一条“最优解”（当前搜索区域中分数最高的候选）。 - 实际是否命中请以返回 JSON 的
matchstate（部分页面可能写作matchState）为准，而不是仅看是否返回了坐标。 - 当候选识别率（相似度）大于等于你传入的阈值（如
matchVal）时，matchstate=true；低于阈值则为false。 All系列只会输出识别率 >= 阈值 的条目，低于阈值的候选会被过滤；业务代码仍建议先判断matchstate再使用坐标。
- 非
十一、快速选型表
| 你的需求 | 优先考虑的接口 |
|---|---|
| 已绑定窗口，只要最佳匹配 | MatchWindowsFromPath / MatchWindowsFromPtr |
| 已绑定窗口，要所有出现位置 | MatchWindowsFromPathAll / MatchWindowsFromPtrAll |
| 线稿/强对比 UI，需颜色模型二值化 | MatchWindowsThreshold* 对应 Path/Ptr/All |
| 源图在内存、模板在文件 | MatchImagePtrFromPath / FindImagePtrFromPath（及 All） |
| 源与模板都在内存、高性能重复跑 | MatchImageFromPtr / FromPtrAll |
| 用色差 + 扫描方向找 第一个 | FindImageFromPath / FindImagePtrFromPath / FindWindowsFromPath（注意 dir） |
| 用色差找 全部 | FindImageFromPathAll / FindImagePtrFromPathAll / FindWindowsFromPathAll |
| GIF/动画直到出现 | MatchAnimationFromPath / MatchAnimationFromPtr |
| 两整张图是否像、SSIM/MSE | CalculateSSIM、CalculateMSE 等 |
更细的参数默认值、JSON 字段与边界条件 以各接口详情页为准；本页用于 名称与系列差异 对照。